home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 October: Mac OS SDK / Dev.CD Oct 96 SDK / Dev.CD Oct 96 SDK2.toast / Development Kits (Disc 2) / OpenDoc / OpenDoc Development / Debugging Support / OpenDoc Source Code / Utilities / Interfaces / DlogUtil.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-04-22  |  11.8 KB  |  311 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        DlogUtil.h
  3.  
  4.     Contains:    function declarations dialog utility functions
  5.  
  6.     Owned by:    Tantek Çelik
  7.  
  8.     Copyright:    © 1993 - 1996 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     Change History (most recent first):
  11.  
  12.          <3>      1/4/96    eeh        fix header
  13.          <2>      1/4/96    eeh        1226961: add ActivateAllControls
  14.  
  15.     To Do:
  16. */
  17.  
  18. #ifndef _DLOGUTIL_
  19. #define _DLOGUTIL_
  20.  
  21. #ifndef _ODTYPES_
  22. #include <ODTypes.h>
  23. #endif
  24.  
  25. #ifndef _STORUTIL_
  26. #include <StorUtil.h>
  27. #endif
  28.  
  29. #ifndef __DIALOGS__
  30. #include <Dialogs.h>
  31. #endif
  32.  
  33. #ifndef __LISTS__
  34. #include <Lists.h>
  35. #endif
  36.  
  37. #ifndef SOM_Module_OpenDoc_Errors_defined
  38. #include "ErrorDef.xh"
  39. #endif
  40.  
  41. #ifndef _ODDEBUG_
  42. #include "ODDebug.h"
  43. #endif
  44.  
  45. #ifndef __SCRIPT__
  46. #include "Script.h"
  47. #endif
  48.  
  49. #ifndef _UTILERRS_
  50. #include "UtilErrs.h"
  51. #endif
  52.  
  53.  
  54. #ifdef __cplusplus
  55. #define DEFAULT(V) =(V)
  56. extern "C" {
  57. #else
  58. #define DEFAULT(V)
  59. #endif
  60.  
  61. //==============================================================================
  62. // Classes Used in Interface
  63. //==============================================================================
  64.  
  65. class ODSession;
  66. class ODMenuBar;
  67. class DialogScriptData;
  68.  
  69. //==============================================================================
  70. // Psuedo-items representing arrow keys and PageUp etc.
  71. //==============================================================================
  72.  
  73. const char kEnterKey        = 0x03;
  74. const char kReturnKey        = 0x0D;
  75. const char kEscapeKey        = 0x1B;
  76. const char kUpArrowKey        = 0x1E;
  77. const char kDownArrowKey    = 0x1F;
  78.  
  79. const ODSShort kODUpArrowItem = -1000;
  80. const ODSShort kODDownArrowItem = -1001;
  81. const ODSShort kODPageUpArrowItem = -1002;
  82. const ODSShort kODPageDownArrowItem = -1003;
  83. const ODSShort kODHomeArrowItem = -1004;
  84. const ODSShort kODEndArrowItem = -1005;
  85.  
  86. //==============================================================================
  87. // Dialog Utility Macros
  88. //==============================================================================
  89.  
  90. #define ODDisposeRoutineDescriptor(r) \
  91.     if ( !r ) ; else DisposeRoutineDescriptor(r)
  92.  
  93. #define ODDisposeDialog(dlg) \
  94.     if ( !dlg ) ; else DisposeDialog(dlg)
  95.  
  96. #if ODDebug
  97.     inline void ASSERT_CONTROL_ITEM( short itemType )
  98.     {
  99.         itemType &= ~kItemDisableBit;
  100.         ASSERT(itemType>=ctrlItem && itemType<=ctrlItem+resCtrl,kODErrAssertionFailed);
  101.     }
  102. #else
  103.     #define ASSERT_CONTROL_ITEM(T)    do{ } while(0)
  104. #endif
  105.  
  106. #define IS_ARROW_KEY(key)                                                        \
  107.     ((ODBoolean) (((key) >= kODEndArrowItem) && ((key) <= kODUpArrowItem)))        \
  108.  
  109. //==============================================================================
  110. // Dialog Utility Functions
  111. //==============================================================================
  112.  
  113. DialogPtr ODGetNewDialog( Environment*, short id, ODSession*,
  114.                             ODBoolean defaultButtons DEFAULT(kODTrue) );
  115.     // Calls GetNewDialog, with preflighting, and sets things up so the filter
  116.     // proc (below) will work. If defaultButtons is true, will call SetDlog-
  117.     // DefaultItem to set up the standard OK and Cancel buttons.
  118.  
  119. ODSShort ShowAlert(Environment *ev, 
  120.                     ODSShort alertID, 
  121.                     ModalFilterUPP modalFilter, 
  122.                     ODSession *session);
  123.     // Calls Alert, with preflighting, and sets things up so standard OpenDoc 
  124.     // filter procs (below) will work.  This function opens the current library's
  125.     // resource fork, so it must not be called when a resource fork is already
  126.     // open.
  127.  
  128. pascal Boolean ODDialogFilterProc( DialogPtr, EventRecord *, short *item );
  129.     // FilterProc to use for dialogs. Forwards update/activate/null/os events
  130.     // to Dispatcher. Handles std keyboard equivs and movable-modal dialogs.
  131.     // You MUST have created the dialog with ODGetNewDialog!
  132.  
  133. ModalFilterUPP GetODDialogFilter( );
  134.     // Returns global UPP for above filter proc; can be passed directly to
  135.     // ModalDialog() or Alert(). Do not dispose this UPP!
  136.  
  137. void ActivateAllControls(DialogPtr dialog, Boolean isActivate);
  138.     // Activate or deactive all dialog items that are controls.
  139.  
  140. pascal Boolean ODArrowKeyFilterProc(DialogPtr dialog, EventRecord *event, short *itemHit);
  141.     // Checks for arrow keys, PageUp, PageDown, Home and End keys, and cmd- and option-
  142.     // modified arrows which are their synonyms.  Sets *itemHit to psuedo-items (negative
  143.     // integers) and returns TRUE when successful, otherwise calls ODButtonKeyFilterProc.
  144.  
  145. ModalFilterUPP GetODArrowKeyFilterProc();
  146.     // Returns global UPP for above filter proc; can be passed directly to
  147.     // ModalDialog(). Do not dispose this UPP!
  148.  
  149. pascal Boolean ODButtonKeyFilterProc(DialogPtr dialog, EventRecord *event, short *itemHit);
  150.     // Checks for return, enter, escape and cmd-period keys (assumes first item is
  151.     // the OK button and the second item is the cancel button).  Call when 
  152.     // ODOutlineDefaultButtonDrawProc  is employed to outline the default buton.
  153.     // The return and enter keys do not exit the dialog if the first item is inactive.
  154.     // Passes other events to ODDialogFilterProc.
  155.  
  156. ModalFilterUPP GetODButtonKeyFilterProc( );
  157.     // Returns global UPP for above filter proc; can be passed directly to
  158.     // ModalDialog(). Do not dispose this UPP!
  159.  
  160. void ODUseCommandKeyStringsResource(short resID);
  161.     // Tells ODButtonKeyFilterProc which STR# resource to use to lookup
  162.     // dialog-specific command keys.  Each string in the STR# resource
  163.     // corresponds by index to each keyable item (button) in the DITL.
  164.     // If the string is "", no command key applies to the item.  Otherwise,
  165.     // the first character of the string is used as the command key code
  166.     // for its corresponding DITL item.  The number of strings in the
  167.     // STR# resource should be less than or equal to the number of items
  168.     // in the DITL resource of the active dialog, or Very Bad Things might
  169.     // happen.
  170.  
  171. void ODDialogBegin( Environment* ev, ODSession* session, 
  172.                     ODMenuBar* currentMenuBar, DialogPtr dialog );
  173.     // Call before ModalDialog, this function removes the Redo menu item so
  174.     // that ModalDialog will know how to enable & disable Cut, Copy & Paste.
  175.     // Must be paired with ODDialogEnd after ModalDialog completes.
  176.  
  177. void ODDialogEnd();
  178.     // Call to cleanly restore the Redo menu item that was deleted in ODDialogBegin.
  179.  
  180. pascal void ODOutlineDefaultButtonDrawProc(DialogPtr theDialog, short theItem);
  181.     // User item draw proc that outlines dialog item 1.
  182.     // Unlike SetDialogDefaultItem, the outline is drawn dim if the button is inactive.
  183.     // If you use this draw proc, be sure to pass kODFalse as the defaultButtons
  184.     // parameter to ODGetNewDialog.
  185.  
  186. UserItemUPP GetODOutlineDefaultButtonDrawProc( );
  187.     // Returns global UPP for above draw proc; can be assigned as an item handle.
  188.     // Do not dispose this UPP!
  189.  
  190. void ODUseDialogScriptData( DialogScriptData* dsd, DialogPtr dialog );
  191.     // set the global to be used by CheckKeyScriptChangeFilterProc
  192.  
  193. pascal ODBoolean CheckKeyScriptChangeFilterProc( DialogPtr dialog,
  194.         EventRecord *event, short *itemHit);
  195.     // Working in cooperation with an instance of DialogScriptData, changes
  196.     // the script/font of a dialog's editable text items when necessary
  197.     // to allow a user to enter text in a non-Roman font.  Since Roman
  198.     // fonts cannot display much non-Roman text, and fonts of one non-Roman
  199.     // script often can't display text of another, we only allow users to
  200.     // switch keyscripts once per dialog, and then only if the starting
  201.     // script is Roman.
  202.     // Note: this filter always returns kODFalse, since it never consumes
  203.     // events.  Call it from your own local filter proc, then pass control
  204.     // to any other filters you need.
  205.  
  206. void EnableOkButton(DialogPtr dlog, ODBoolean enable);
  207.     // Enables or disables the first dialog item and invalidates the area occupied
  208.     // by a default frame around the button.  Should be used to disable the deafult
  209.     // button when ODOutlineDefaultButtonDrawProc is used to outline the button.
  210.  
  211. pascal void DrawGrayBoxItem(DialogPtr theDialog, short theItem);
  212. pascal void DrawItemFrame(DialogPtr theDialog, short theItem);
  213.     // UserItem procs that draw gray or black boxes around items.
  214.  
  215. void FlashButtonItem( DialogPtr dialog, short itemHit );
  216.     // Flash the button in the dialog (used to indicate that a command key
  217.     // combination has selected it.
  218.  
  219. ODBoolean DrawITextInDlogBox( ODIText* itext, const Rect* textRect,
  220.         DialogPtr dlog, ODBoolean tryToTruncate );
  221.     // Given a dialog, a rect and an ODIText*, truncate the text to fit in the
  222.     // rect and then draw it in the dialog.  Return true if any change made to
  223.     // the text (ie. if it was truncated).
  224.  
  225. void ArrowKeyScrollList( ODSShort arrowItem, ListHandle listH,
  226.         ODSShort pageSize, ODSShort lastEntry );
  227.     // Given an "item" representing an up or down arrow or any of the other keys
  228.     // recognized by ODArrowKeyFilterProc above, a ListHandle indicating the list
  229.     // in which scrolling is taking place, pageSize giving the number of entries to
  230.     // be skipped by a "page down" command, and the zero-based index of the last
  231.     // entry in the list, do the right thing for the key selected.  So far this
  232.     // routine is used for lists embedded in dialogs, and it's up to the caller
  233.     // to determine which list is meant if there is more than one.
  234.     // NOTE that nothing happens currently if no list item is selected.  There needs
  235.     // to be a starting point for scrolling.
  236.  
  237. void ReplaceIntoString(ODSShort strResourceID,
  238.                         ConstStr255Param str0,
  239.                         ConstStr255Param str1,
  240.                         Str255 destString);
  241.     // Substitutes str0 for all occurances of "^0", and str1 for "^1", in the 
  242.     // string retrieved from the 'STR ' resource identified by the first parameter.
  243.     // Either str0 or str1 may be null, and str0 or str1 may be the same string
  244.     // as destString.
  245.  
  246. ODIText* GetODITextInd(short resID, short index);
  247.     // Gets string # (index) from the 'STR#' resource given by resID 
  248.     // into an IText* whose script and language codes are those of 
  249.     // the current system script.
  250.     // You MUST first call BeginUsingLibraryResources or CUsingLibraryResources!
  251.  
  252. ODIText* GetODIText(short resID);
  253.     // Gets the 'STR ' resource given by resID into an IText* whose script
  254.     // and language codes are those of the current system script.
  255.     // You MUST first call BeginUsingLibraryResources or CUsingLibraryResources!
  256.  
  257. void SetDialogTextStyle(DialogPtr dlg, short finfResourceID,
  258.         ODScriptCode script);
  259.     // Sets the font, styl, and size of the argument dialog according to the
  260.     // 'finf' resource identified by the second parameter.
  261.     // script parameter overrides what's in the finf resource; intended for
  262.     // language kit cases where the default script is Roman but we need to
  263.     // display text Roman fonts can't handle.  Pass smCurrentScript if you
  264.     // want this param ignored.
  265.  
  266. void SetPopupItemScript(MenuHandle menu, short itemNum, short scriptID);
  267.     // Sets the script of an item in a popup menu, which is assumed to be
  268.     // drawn using the font of the current port.
  269.     // "scriptID" should be a true script code, not an implicit script code
  270.  
  271.  
  272.     // This class provided the state required by clients of
  273.     // CheckKeyScriptChangeFilterProc above.  Typically they'll need
  274.     // to instantiate a member of the class, pass it to ODUseDialogScriptData
  275.     // (also above), and then create and use a custom FilterProc that
  276.     // calls CheckKeyScriptChangeFilterProc.  Since CheckKeyScriptChangeFilterProc
  277.     // always returns false, the custom filter proc should be prepared to
  278.     // call some other filter proc in addition.
  279. const short kMaxNumItems = 32;    // max number of items in a dialog
  280. const short ksmUninited = -4;
  281. class DialogScriptData
  282. {
  283.   public:
  284.     DialogScriptData();
  285.     ODVMethod    ~DialogScriptData();
  286.     ODMethod    void SetScriptAndLockKeyboard();
  287.     ODMethod    void SetDialog(DialogPtr dlg)    { fDialog = dlg; }
  288.     ODMethod    void SetScriptAndLockKeyboard( ODScriptCode script );
  289.     ODMethod    ODBoolean ScriptChanged()    { return fMustUnlock; }
  290.     ODMethod    ODBoolean ItemRedrawn( short item );
  291.     ODMethod    void SetRedrawn( short item );
  292.     ODMethod    ODScriptCode Script()    { return fScript; }
  293.     ODMethod    ODLangCode Language()
  294.             { return GetScriptVariable(fScript, smScriptLang); }
  295.  
  296.   protected:
  297.     ODMethod    void ReleaseLockout();
  298.  
  299.   private:
  300.     ODScriptCode fScript;
  301.     ODBoolean fMustUnlock;
  302.     ODULong fItemRedrawn;            // bit vector of items changed
  303.     DialogPtr fDialog;
  304. };
  305.  
  306. #ifdef __cplusplus
  307. }
  308. #endif
  309.  
  310. #endif // _DLOGUTIL_
  311.